Alternatively, I could organize them by type first, instead of including the type after the term, in parentheses. Not sure which would be preferable.

EDIT: Also, in a perfect world, there would be some way to access the relevant place within the associated YAML file, like "source" links in Sphinx-generated documentation.

Had a quick look and am generally in favor of this, as it might help users in general.

Does that make the entities appendix page rerundant though?

I could organize them by type first, instead of including the type after the term, in parentheses. Not sure which would be preferable.

A way to dynamically sort / filter them by type or whatever other criterion would be the best but not sure how feasible it is in MkDocs and would have to be nuked for the PDF rendering.

I would start with alphabetical and progressively improve later.

Does that make the entities appendix page rerundant though?

I don't think this makes the "entities" appendix redundant - these are essentially different pieces of information, aren't they?

I would start with alphabetical and progressively improve later.

agreed!

nuked for the PDF rendering.

@tsalo could you please rebase this PR on master (or merge master) so that we can see how the rendered PDF looks like?

Thanks!

A way to dynamically sort / filter them by type or whatever other criterion would be the best

@Remi-Gau that's definitely in the wishlist, along with links back to sections of the specification that use each term.

I would start with alphabetical and progressively improve later.

Sounds good. I'll keep it as-is then.

@tsalo could you please rebase this PR on master (or merge master) so that we can see how the rendered PDF looks like?

@sappelhoff done!

Does that make the entities appendix page rerundant though?

I don't think this makes the "entities" appendix redundant - these are essentially different pieces of information, aren't they?

Well let's just say that the entities page is a subset of the glossary. See the example of the hemisphere entity below.

• https://bids-specification--923.org.readthedocs.build/en/923/99-appendices/09-entities.html#hemi

• https://bids-specification--923.org.readthedocs.build/en/923/99-appendices/14-glossary.html#hemisphere-entities

I don' think it is necessarily an issue though.

Eventually, it would be great to have the glossary replace the Entities appendix. Imagine hovering your mouse over a term in the specification and the glossary entry pops up! However, at the moment, I think the glossary is just too big and difficult to navigate for users to rely on it for something as common as checking entity definitions.

EDIT: There are some plugins that should make hover tooltips possible, like md-tooltips, md-tooltips-link, and mkdocs-tooltips.

@sappelhoff would you rather I wait on @effigies's review or can we merge now that there are two approvals?

Let's merge :-) 🚀 Thanks @tsalo